Skip to content

Improvement: refine UI input method contracts & component documentation#11707

Open
GitHamo wants to merge 2 commits into
ILIAS-eLearning:trunkfrom
GitHamo:improvement/declare-methods-in-ui-component-interfaces
Open

Improvement: refine UI input method contracts & component documentation#11707
GitHamo wants to merge 2 commits into
ILIAS-eLearning:trunkfrom
GitHamo:improvement/declare-methods-in-ui-component-interfaces

Conversation

@GitHamo

@GitHamo GitHamo commented Jun 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

This PR enhances method signatures in the UI component Input interfaces.

The changes include:

  • getStepSize(): Added contract definition to Numeric interface.
  • getDedicatedName(): Added contract definition to Input interface.
  • Corrected dockblock in UI\Component\Component.

Note: declared methods already exist in related implementations.

Why are these methods needed in the public contracts?

ILIAS\Component\Activities\Activity::getInputDescription() exposes the UI input description that serves as a machine-readable schema for activity input validation. [L]

As part of the new ILIAS Webservices component, we plan to consume the input description from the activities in REST endpoints. We currently want to use this schema in two places:

getDedicatedName()

getDedicatedName() is used to reconstruct the input mapping and validate incoming webservice requests against the expected form input names.

Example:

/**
 * @var \ILIAS\UI\Factory $factory
 * @var \ILIAS\Component\Activities\Activity $activity
 * @var \ILIAS\UI\Component\Input\Container\Form\FormInput $inputDescription
 * @var array<\ILIAS\UI\Component\Input\Container\Form\FormInput> $inputs
 */
$inputDescription = $activity->getInputDescription();
$inputs = $inputDescription->getInputs();

// Reconstruct associative array using dedicated names to ensure form mapping works correctly.
$namedInputs = [];

foreach ($inputs as $input) {
    $dedicatedName = $input->getDedicatedName();
    $key = ($dedicatedName !== null && $dedicatedName !== '')
        ? $dedicatedName
        : $input->getLabel();

    $namedInputs[$key] = $input;
}

$form = $factory->input()
    ->container()
    ->form()
    ->standard('', $namedInputs);

getStepSize()

getStepSize() is used to determine the appropriate OpenAPI numeric type (integer or number) when generating the API specification.

See: https://swagger.io/docs/specification/v3_0/data-models/data-types/#numbers

Example:

/** @var \ILIAS\UI\Component\Input\Input $input */
$stepSize = (float) $input->getStepSize();
$hasPrecision = (floor($stepSize) !== $stepSize);

$type = $hasPrecision ? 'number' : 'integer';
$format = $hasPrecision ? 'double' : '';

Existing public implementations

The proposed methods are already declared public in their corresponding implementation classes:

  • ILIAS\UI\Implementation\Component\Input\Input::getDedicatedName() (also has @inheritdoc)
  • ILIAS\UI\Implementation\Component\Input\Field\Numeric::getStepSize()

This change adds them to the corresponding interfaces so consumers of getInputDescription() can rely on the public contracts instead of concrete implementation classes.

@GitHamo GitHamo marked this pull request as ready for review June 26, 2026 12:23
@mjansenDatabay mjansenDatabay added the php Pull requests that update Php code label Jun 30, 2026
thibsy
thibsy reviewed Jun 30, 2026
View reviewed changes

@thibsy thibsy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @GitHamo,

Thx a lot for your contribution to the UI framework!

Please help me answer the following questions:

  • Public getters: you expose the getStepSize() and getDedicatedName() getters on the public interface. Could you explain why you need those methods when working with the inputs? What is your use-case? We normally try and keep most of our getters strictly internal, so if there is not an important reason, we would like to keep it this way.

Kind regards,
@thibsy (as UI coordinator)

@GitHamo GitHamo force-pushed the improvement/declare-methods-in-ui-component-interfaces branch from aa5ba21 to 0d22f10 Compare June 30, 2026 14:11
@GitHamo

GitHamo commented Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

Hi @thibsy, thank you very much for your comment. I have updated the PR description with the concrete use cases that require these methods.

We are working on a new webservices component that consumes the UI input description exposed through ILIAS\Component\Activities\Activity::getInputDescription() [L]

The declared methods are already public in related implementations, and I could just use the implementation signature directly, but I prefer to use the interface instead since we want to keep the domain & infrastructure layers overlap to a minimum.

One of the methods even has an @inheritdoc PHPDoc, which suggests it may have originally been intended to be part of the public contract.

  • ILIAS\UI\Implementation\Component\Input\Input: declared public, has phpdoc @inheritdoc
  • ILIAS\UI\Implementation\Component\Input\Field\Numeric: declared public

Please let me know if I should clarify anything.

Cheers,
Ahmed

@thibsy

thibsy commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

Hi @GitHamo,

thx for your detailed feedback.

I will need some time to digest this together with @chfsx, because we are unsure if the UI inputs should be used directly in this instance. We can see how a looser coupling between UI and Component (Activities), achieved by something equivalent of the GS, could be beneficial.

Regarding your comment

[...] I could just use the implementation signature directly, but I prefer to use the interface instead [...].

I think this is the wrong mindset =). We take our interface segregation very seriously inside the UI framework, there is even a whole paper about it. Just because you can access it, doesn't mean you ever should. This is clearly a mismatch of our APIs. I know that you brought this to our attention now, but just for future reference, you should not reach into internals of other components without contacting respective authorities, especially if you are in an advanced stage of your implementation.

Kind regards,
@thibsy

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@thibsy thibsy thibsy left review comments

Assignees

@thibsy thibsy

Labels

improvement kitchen sink php Pull requests that update Php code

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@GitHamo @thibsy @mjansenDatabay @oliversamoila